\section{Technicalities}

\subsection{Source Code Documentation}

To access the source code documentation point your
web browser to:

\begin{itemize}
\item \href{http://godoc.org/code.google.com/p/phylofriend}{http://godoc.org/code.google.com/p/phylofriend}
\end{itemize}

If you want to modify the source code it is best to
use \emph{godoc} locally on your computer.

\begin{enumerate}
\item If \emph{godoc} is not yet installed install it by typing\\
	\texttt{sudo apt-get install golang-go.tools}\\
	(Linux Mint)
\item Start the documentation web server with\\
	\texttt{godoc -http=:6060}
\item Point your web browser to \texttt{localhost:6060}.
\item Click on \emph{Packages} and search for \emph{phylofriend}.
\end{enumerate}

This will give you a nice overview of the internal program
documentation. You can also click on function names to browse
the source code.


\subsection{Mutation Model}

The two basic mutation models are the infinite alleles model
and the stepwise mutation model as explained by Bruce Walsh\cite{Wal02}.
Phylofriend uses a hybrid mutation model. Most markers are
calculated using the stepwise model, palindromic markers are
calculated as described in \cite{Can14}.

As the method for calculating the genetic distance is likely
to change with time please look at the internal program
documentation if you need more details.


\subsection{Mutation Rates}

The directory \emph{phylofriend/mutationrates} contains
files with predefined mutation rates.

\subsection*{All 1 Mutation Rates}

\begin{itemize}
\item 12-1.txt
\item 37-1.txt
\item 67-1.txt
\item 111-1.txt
\end{itemize}

In these files all mutation rates are set to 1 for the
corresponding set of markers. They are useful for simple
mutation counting.


\subsection*{Average Mutation Rates}

\begin{itemize}
\item 12-average.txt
\item 37-average.txt
\item 67-average.txt
\item 111-average.txt
\end{itemize}

In these files average mutation rates are used for the
corresponding set of markers. The mutation rates were taken
from \cite{Kly12}. The distance matrix contains years but
these years should not be interpreted as TMRCA (Time to Most
Recent Common Ancestor). It is more like a \emph{How long
do I have to wait on average before such a genetic distance
occurs?}

These mutation rates are useful for genealogical purposes.
During genealogical time frames (about 500 years) long time
stable markers rarely change. If such an event happens a
son may be immediately 1000 years away from his father in
terms of genetic distance. This is a correct result because
mutations are governed by coincidence and such events do
happen from time to time but it does not make much sense
to place a son far away from his family. So very stable
markers are purposely underweighted by using average
values.


\subsection*{12 Marker Single Mutation Rates}

\begin{itemize}
\item 12.txt
\item 37-12.txt
\item 67-12.txt
\item 111-12.txt
\end{itemize}

These files are basically the same as the average mutation
rates files but for the first 12 markers the mutation rates
are set per marker. This puts on the appropriate weight on
very stable markers. The mutation rates were taken from
Wikipedia\cite{Wiki-List_of_DYS_markers}. Although there
may be some doubt if data from Wikipedia can be trusted 
the first 12 markers are well known and they are in use
for a long time. So I just adopted them. The values should be
good enough for most purposes.

For each file the 12 marker mutation rates were multiplied
by a calibration factor so that their average value matches
that from the rest of the file.

These files are useful for deeper history or if you
observe changes on long time stable markers. If several
persons share the same value on a very stable marker they
probably belong together. So try these mutation rates to
see if the results make more sense than those obtained by
using average markers.


\subsection{CSV Input Format}

Example:

\begin{verbatim}
id1,"Dirk Struve",Germany,R1b-CTS4528,13,24,14,11,11-14,12,...
id2,"Pyl. O. Friend",Germany,R1b-CTS4528,13,24,14,11,11-14,...
\end{verbatim}

When importing a file in comma separated values format the
first column must contain IDs. An arbitrary number of columns
containing custom information may follow. The last columns
must contain at least 12 Y-STR values in Family Tree DNA order.
Rows containing comments are allowed.

Phylofriend will always try to parse the file as best as
it can.


\subsection{Text Format}

Example:

\begin{verbatim}
Dirk_Struv	13	24	14	11	11	14	12	12	12	12	14	28
Pyl._O._Fr	13	24	14	11	11	14	12	12	12	12	14	28
\end{verbatim}

The text format is a simplified format intended for easy
parsing and to work well with other programs. For compatibility
reasons the first column is exactly 10 characters long and
contains only non Unicode characters. Spaces are transformed into
underscores. The following columns contain Y-STR values
separated by tabs.


\subsection{PHYLIP Format}

Example:

\begin{verbatim}
2
Dirk_Struv	0	0
Pyl._O._Fr	0	0
\end{verbatim}

The first line contains the number of entries. An entry
line contains an ID that is 10 characters long and contains
only non Unicode characters. Spaces are transformed into
underscores. The columns containing genetic distances
are separated by tabs. For readability reasons
Phylofriend writes only integers. If you need more precision
you can scale the distance by using the \emph{cal} option.







